Update pipeline documentation, both public facing and internal#644
Update pipeline documentation, both public facing and internal#644juaristi22 merged 10 commits intomainfrom
Conversation
juaristi22
force-pushed
the
maria/methodology-docs
branch
2 times, most recently
from
6493e3a to
4479b78
Compare
baogorek
left a comment
baogorek
left a comment
There was a problem hiding this comment.
Hi @juaristi22 this is great work! Please see comments. I know you're documenting a very malleable product here. I didn't get a chance to go through every line in the Jupyter notebooks, and I don't think I'll need to, but I'd like to see them one more time after you rebase and address the comments. Also, please consider whether you do want to include changes to the python files in here that control the modal job and data build.
…ll diagnostics to HF - docs/methodology.md and docs/data.md updated to match current pipeline - pipeline.py now uploads validation diagnostics after H5 builds complete, in addition to the existing calibration diagnostics upload Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- Move docs/calibration_internals.ipynb → docs/internals/calibration_package_internals.ipynb - Add docs/internals/data_build_internals.ipynb: Stage 1 coverage — clone creation with real assign_random_geography() on 20 records, source imputation concept demo, PUF cloning toy walkthrough - Add docs/internals/local_dataset_assembly_internals.ipynb: Stages 3–4 — Hard Concrete L0 math, λ preset comparison, weight expansion reference, diagnostics column guide - Add docs/internals/README.md: navigation index + §9 pipeline orchestration (run ID format, Modal volumes, step dependency graph, resume logic, HuggingFace artifact paths, meta.json structure) - Extend calibration_package_internals with Part 4 (matrix assembly per-state, domain constraints) and Part 5 (takeup randomization cross-stage demo) - All notebooks execute with zero errors under --allow-errors; toy inputs complete in <30s - Add changelog fragment Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
juaristi22
force-pushed
the
maria/methodology-docs
branch
from
af3d5b8 to
0da4048
Compare
|
Moved the changes to the pipeline to PR #700 and updated documentation with last week's changes! |
baogorek
left a comment
baogorek
left a comment
There was a problem hiding this comment.
The changes to the python files appear to be in-line documentation or deleting dead code. I could have read the notebooks more closely, but it's good stuff and I don't want to delay getting it in. Approved.
2 participants
Summary
Comprehensive update to pipeline documentation — both public-facing and internal developer reference. FIxes #643 .
Internal developer reference (
docs/internals/)Three new notebooks providing thorough explanations of the calibration pipeline for developers:
data_build_internals.ipynb— Stage 1: PUF cloning, geography assignment (including AGI-conditional routing and the no-collision constraint), and source imputation. Corrected pipeline ordering to match implementation (PUF clone → geography → source imputation). Documents that geography is rederived per-run, not persisted.calibration_package_internals.ipynb— Stage 2: Matrix construction internals including per-state simulation, clone loop, domain constraints (corrected: constraints come fromstratum_constraintsinpolicy_data.db, nottarget_config.yaml), takeup re-randomization (state precomputation + clone-loop draws), county-dependent variables, COO assembly, target config filtering (clarified: applied post-matrix-build, not during construction), hierarchical uprating, and calibration package serialization with initial weight computation.optimization_and_local_dataset_assembly_internals.ipynb— Stages 3–4: L0 optimization (fixed sparsity demo from 20→200 records so lambda effect is visible), H5 assembly pipeline (expanded from 11→16 steps matching actual implementation), SPM threshold recalculation, takeup consistency invariant, and diagnostics includingvalidation_results.csv.README.md— Pipeline orchestration reference with run ID format, step dependency graph, Modal volumes, HuggingFace artifact paths, resume logic. Added file reference tables forcalibration/andmodal_app/with per-file descriptions and notes on legacy/standalone status.Public-facing documentation
docs/methodology.md— Minor updates to reflect current implementation.docs/data.md— Updated data source descriptions.Dead code removed
save_geography()andload_geography()fromclone_and_assign.py— defined but never called by any pipeline code. Geography is rederived each run via deterministic seeding, making serialization unnecessary.Test plan
ruff format --check .passesunified_matrix_builder.py,unified_calibration.py,publish_local_area.py,clone_and_assign.py)🤖 Generated with Claude Code